import {ConditionBuilder} from './ConditionBuilder';
import {
  DeleteBuilder,
  LOGICAL_OPERATOR,
  LogicalOperator,
  SelectBuilder,
  SqlBuilderExtensions,
  UpdateBuilder
} from '../builders';

/**
 * SqlFilter工具类
 * 提供更简便的方式创建和组合条件
 *
 * @example
 * // 基本使用
 * const filter = SqlFilter.create<User>()
 *   .eq('status', 'active')
 *   .gt('age', 18);
 *
 * // 从对象创建
 * const filter = SqlFilter.fromObject({ status: 'active', isVIP: true });
 *
 * // 应用到查询构建器
 * const query = userSql.select();
 * filter.applyTo(query);
 * const result = query.execute();
 */
export class SqlFilter<T = any> {
  /** 条件构建器 */
  private builder: ConditionBuilder<T>;

  /**
   * 构造函数
   * @param tableAlias 表别名（可选）
   * @param extensions SQL构建器扩展（可选）
   */
  constructor(tableAlias?: string, extensions?: SqlBuilderExtensions) {
    this.builder = new ConditionBuilder<T>(tableAlias, extensions);
  }

  /**
   * 创建一个新的SqlFilter实例
   *
   * @example
   * // 创建用户筛选器，设置表别名
   * const filter = SqlFilter.create<User>('u');
   *
   * @param tableAlias 表别名（可选）
   * @param extensions SQL构建器扩展（可选）
   * @returns 新的SqlFilter实例
   */
  public static create<E = any>(tableAlias?: string, extensions?: SqlBuilderExtensions): SqlFilter<E> {
    return new SqlFilter<E>(tableAlias, extensions);
  }

  /**
   * 创建一个空的条件构建器
   *
   * @example
   * // 创建空的用户筛选器
   * const emptyFilter = SqlFilter.empty<User>();
   *
   * @returns 一个没有任何条件的新SqlFilter
   */
  public static empty<E = any>(): SqlFilter<E> {
    return new SqlFilter<E>();
  }

  /**
   * 从条件对象创建过滤器
   *
   * @example
   * // 从对象创建用户筛选器
   * const userConditions = { status: 'active', role: 'admin' };
   * const filter = SqlFilter.fromObject<User>(userConditions);
   * // 相当于: WHERE status = 'active' AND role = 'admin'
   *
   * @param condition 条件对象
   * @returns 包含对象属性条件的SqlFilter实例
   */
  public static fromObject<E = any>(condition: Partial<E>): SqlFilter<E> {
    return new SqlFilter<E>().where(condition);
  }

  /**
   * 获取条件构建器
   *
   * @returns 内部的ConditionBuilder实例
   */
  public getBuilder(): ConditionBuilder<T> {
    return this.builder;
  }

  /**
   * 添加等于条件
   *
   * @example
   * // 添加等于条件
   * filter.eq('status', 'active');
   * // 生成: status = 'active'
   *
   * @param field 字段名
   * @param value 值
   * @returns 当前过滤器实例，支持链式调用
   */
  public eq(field: keyof T | string, value: any): this {
    this.builder.eq(field, value);
    return this;
  }

  /**
   * 添加不等于条件
   *
   * @example
   * // 添加不等于条件
   * filter.ne('status', 'inactive');
   * // 生成: status <> 'inactive'
   *
   * @param field 字段名
   * @param value 值
   * @returns 当前过滤器实例，支持链式调用
   */
  public ne(field: keyof T | string, value: any): this {
    this.builder.ne(field, value);
    return this;
  }

  /**
   * 添加大于条件
   *
   * @example
   * // 添加大于条件
   * filter.gt('age', 18);
   * // 生成: age > 18
   *
   * @param field 字段名
   * @param value 值
   * @returns 当前过滤器实例，支持链式调用
   */
  public gt(field: keyof T | string, value: any): this {
    this.builder.gt(field, value);
    return this;
  }

  /**
   * 添加大于等于条件
   *
   * @example
   * // 添加大于等于条件
   * filter.gte('score', 60);
   * // 生成: score >= 60
   *
   * @param field 字段名
   * @param value 值
   * @returns 当前过滤器实例，支持链式调用
   */
  public gte(field: keyof T | string, value: any): this {
    this.builder.gte(field, value);
    return this;
  }

  /**
   * 添加小于条件
   *
   * @example
   * // 添加小于条件
   * filter.lt('price', 100);
   * // 生成: price < 100
   *
   * @param field 字段名
   * @param value 值
   * @returns 当前过滤器实例，支持链式调用
   */
  public lt(field: keyof T | string, value: any): this {
    this.builder.lt(field, value);
    return this;
  }

  /**
   * 添加小于等于条件
   *
   * @example
   * // 添加小于等于条件
   * filter.lte('quantity', 50);
   * // 生成: quantity <= 50
   *
   * @param field 字段名
   * @param value 值
   * @returns 当前过滤器实例，支持链式调用
   */
  public lte(field: keyof T | string, value: any): this {
    this.builder.lte(field, value);
    return this;
  }

  /**
   * 添加LIKE条件
   *
   * @example
   * // 添加LIKE条件
   * filter.like('name', 'john');
   * // 生成: name LIKE '%john%'
   *
   * @param field 字段名
   * @param value 值
   * @returns 当前过滤器实例，支持链式调用
   */
  public like(field: keyof T | string, value: string): this {
    this.builder.like(field, value);
    return this;
  }

  /**
   * 添加IN条件
   *
   * @example
   * // 添加IN条件
   * filter.in('status', ['active', 'pending']);
   * // 生成: status IN ('active', 'pending')
   *
   * @param field 字段名
   * @param values 值数组
   * @returns 当前过滤器实例，支持链式调用
   */
  public in(field: keyof T | string, values: any[]): this {
    this.builder.in(field, values);
    return this;
  }

  /**
   * 添加NOT IN条件
   *
   * @example
   * // 添加NOT IN条件
   * filter.notIn('category', ['archived', 'deleted']);
   * // 生成: category NOT IN ('archived', 'deleted')
   *
   * @param field 字段名
   * @param values 值数组
   * @returns 当前过滤器实例，支持链式调用
   */
  public notIn(field: keyof T | string, values: any[]): this {
    this.builder.notIn(field, values);
    return this;
  }

  /**
   * 添加IS NULL条件
   *
   * @example
   * // 添加IS NULL条件
   * filter.isNull('deletedAt');
   * // 生成: deletedAt IS NULL
   *
   * @param field 字段名
   * @returns 当前过滤器实例，支持链式调用
   */
  public isNull(field: keyof T | string): this {
    this.builder.isNull(field);
    return this;
  }

  /**
   * 添加IS NOT NULL条件
   *
   * @example
   * // 添加IS NOT NULL条件
   * filter.isNotNull('email');
   * // 生成: email IS NOT NULL
   *
   * @param field 字段名
   * @returns 当前过滤器实例，支持链式调用
   */
  public isNotNull(field: keyof T | string): this {
    this.builder.isNotNull(field);
    return this;
  }

  /**
   * 添加BETWEEN条件
   *
   * @example
   * // 添加BETWEEN条件
   * filter.between('age', 18, 30);
   * // 生成: age BETWEEN 18 AND 30
   *
   * @param field 字段名
   * @param min 最小值
   * @param max 最大值
   * @returns 当前过滤器实例，支持链式调用
   */
  public between(field: keyof T | string, min: any, max: any): this {
    this.builder.between(field, min, max);
    return this;
  }

  /**
   * 添加NOT BETWEEN条件
   *
   * @example
   * // 添加NOT BETWEEN条件
   * filter.notBetween('price', 100, 200);
   * // 生成: price NOT BETWEEN 100 AND 200
   *
   * @param field 字段名
   * @param min 最小值
   * @param max 最大值
   * @returns 当前过滤器实例，支持链式调用
   */
  public notBetween(field: keyof T | string, min: any, max: any): this {
    this.builder.notBetween(field, min, max);
    return this;
  }

  /**
   * 从对象添加条件
   *
   * @example
   * // 从对象添加条件
   * filter.where({ status: 'active', isVip: true });
   * // 生成: status = 'active' AND isVip = true
   *
   * @param obj 条件对象
   * @returns 当前过滤器实例，支持链式调用
   */
  public where(obj: Partial<T>): this {
    this.builder.whereObject(obj);
    return this;
  }

  /**
   * 设置下一个条件使用AND连接
   *
   * @example
   * // 使用AND连接条件
   * filter.eq('status', 'active').and().gt('age', 18);
   * // 生成: status = 'active' AND age > 18
   *
   * @returns 当前过滤器实例，支持链式调用
   */
  public and(): this {
    // 不需要实际操作，因为AND是默认的逻辑操作符
    return this;
  }

  /**
   * 设置下一个条件使用OR连接
   *
   * @example
   * // 使用OR连接条件
   * filter.eq('status', 'active').or().eq('status', 'pending');
   * // 生成: status = 'active' OR status = 'pending'
   *
   * @returns 当前过滤器实例，支持链式调用
   */
  public or(): this {
    this.builder.or();
    return this;
  }

  /**
   * 添加日期等于今天条件
   *
   * @example
   * // 添加日期等于今天条件
   * filter.today('createdAt');
   * // 生成: DATE(createdAt) = DATE('now')
   *
   * @param field 日期字段名
   * @returns 当前过滤器实例，支持链式调用
   */
  public today(field: keyof T | string): this {
    this.builder.dateIsToday(field);
    return this;
  }

  /**
   * 添加日期在过去N天内条件
   *
   * @example
   * // 添加日期在过去30天内条件
   * filter.recentDays('lastLogin', 30);
   * // 生成: lastLogin >= date('now', '-30 days')
   *
   * @param field 日期字段名
   * @param days 天数
   * @returns 当前过滤器实例，支持链式调用
   */
  public recentDays(field: keyof T | string, days: number): this {
    this.builder.dateInLastDays(field, days);
    return this;
  }

  /**
   * 添加大小写不敏感的包含条件
   *
   * @example
   * // 添加大小写不敏感的包含条件
   * filter.contains('name', 'john');
   * // 生成: name LIKE '%john%' COLLATE NOCASE
   *
   * @param field 字段名
   * @param value 值
   * @returns 当前过滤器实例，支持链式调用
   */
  public contains(field: keyof T | string, value: string): this {
    this.builder.contains(field, value);
    return this;
  }

  /**
   * 合并另一个过滤器
   *
   * @example
   * // 合并两个过滤器
   * const statusFilter = SqlFilter.fromObject({ status: 'active' });
   * const ageFilter = SqlFilter.create<User>().gt('age', 18);
   * statusFilter.merge(ageFilter);
   * // 生成: status = 'active' AND age > 18
   *
   * // 使用OR合并
   * statusFilter.merge(ageFilter, 'OR');
   * // 生成: status = 'active' OR age > 18
   *
   * @param filter 要合并的过滤器
   * @param logicalOperator 合并使用的逻辑操作符
   * @returns 当前过滤器实例，支持链式调用
   */
  public merge(filter: SqlFilter<T>, logicalOperator: LogicalOperator = LOGICAL_OPERATOR.AND): this {
    this.builder.combine(filter.getBuilder(), logicalOperator);
    return this;
  }

  /**
   * 优化条件
   *
   * @example
   * // 优化条件 - 合并相同字段的IN条件
   * filter
   *   .in('status', ['active', 'pending'])
   *   .or()
   *   .in('status', ['new'])
   *   .optimize();
   * // 自动优化为: status IN ('active', 'pending', 'new')
   *
   * @returns 当前过滤器实例，支持链式调用
   */
  public optimize(): this {
    this.builder.optimize();
    return this;
  }

  /**
   * 将过滤器应用到SQL构建器
   *
   * @example
   * // 应用过滤器到查询构建器
   * const filter = SqlFilter.create<User>()
   *   .eq('status', 'active')
   *   .gt('age', 18);
   *
   * const query = userSql.select();
   * filter.applyTo(query);
   * // 查询构建器现在包含filter的条件
   *
   * @param sqlBuilder SQL构建器
   */
  public applyTo(sqlBuilder: SelectBuilder<T> | UpdateBuilder<T> | DeleteBuilder<T>): void {
    // 获取构建器中的条件和参数
    const conditions = this.builder.getConditions();
    const parameters = this.builder.getParameters();

    // 复制条件和参数到SQL构建器
    for (const condition of conditions) {
      sqlBuilder['conditions'].push(condition);
    }

    // 复制参数
    Object.assign(sqlBuilder['parameters'], parameters);
  }

  /**
   * 从请求参数构建过滤条件
   * 自动处理常见查询参数格式
   *
   * @example
   * // URL查询参数: ?status=active&age_gt=18&category_in=A,B,C
   * const params = {
   *   status: 'active',      // 等于
   *   age_gt: '18',          // 大于
   *   category_in: 'A,B,C'   // 包含于
   * };
   *
   * const filter = SqlFilter.fromParams<User>(params);
   * // 生成: status = 'active' AND age > 18 AND category IN ('A', 'B', 'C')
   *
   * @param params 请求参数对象
   * @returns 构建的过滤器
   */
  public static fromParams<E>(params: Record<string, any>): SqlFilter<E> {
    const filter = new SqlFilter<E>();

    if (!params || typeof params !== 'object') {
      return filter;
    }

    // 处理所有参数
    for (const [key, value] of Object.entries(params)) {
      // 跳过空值
      if (value === undefined || value === null || value === '') {
        continue;
      }

      // 检查是否有操作符后缀
      const parts = key.split('_');
      const operatorSuffix = parts.length > 1 ? parts[parts.length - 1] : null;

      // 如果有操作符后缀，移除后缀获取字段名
      const field = operatorSuffix && [
        'eq', 'ne', 'gt', 'gte', 'lt', 'lte',
        'like', 'in', 'notin', 'between', 'notbetween',
        'isnull', 'isnotnull'
      ].includes(operatorSuffix)
        ? parts.slice(0, -1).join('_')
        : key;

      // 根据操作符后缀添加相应条件
      switch (operatorSuffix) {
        case 'eq':
          filter.eq(field, value);
          break;
        case 'ne':
          filter.ne(field, value);
          break;
        case 'gt':
          filter.gt(field, value);
          break;
        case 'gte':
          filter.gte(field, value);
          break;
        case 'lt':
          filter.lt(field, value);
          break;
        case 'lte':
          filter.lte(field, value);
          break;
        case 'like':
          filter.like(field, value);
          break;
        case 'in':
          // 支持逗号分隔的值列表
          filter.in(field, typeof value === 'string' ? value.split(',') : Array.isArray(value) ? value : [value]);
          break;
        case 'notin':
          // 支持逗号分隔的值列表
          filter.notIn(field, typeof value === 'string' ? value.split(',') : Array.isArray(value) ? value : [value]);
          break;
        case 'between':
          // 支持逗号分隔的两个值
          if (typeof value === 'string' && value.includes(',')) {
            const [min, max] = value.split(',');
            filter.between(field, min, max);
          }
          break;
        case 'notbetween':
          // 支持逗号分隔的两个值
          if (typeof value === 'string' && value.includes(',')) {
            const [min, max] = value.split(',');
            filter.notBetween(field, min, max);
          }
          break;
        case 'isnull':
          if (value === true || value === 'true' || value === '1') {
            filter.isNull(field);
          }
          break;
        case 'isnotnull':
          if (value === true || value === 'true' || value === '1') {
            filter.isNotNull(field);
          }
          break;
        default:
          // 没有操作符后缀，默认使用等于
          filter.eq(field, value);
          break;
      }
    }

    return filter;
  }

  /**
   * 添加左模糊匹配条件（匹配以特定字符结尾的字符串）
   *
   * @example
   * // 添加左模糊匹配条件
   * filter.likeLeft('email', 'gmail.com');
   * // 生成: email LIKE '%gmail.com'
   *
   * // 匹配结尾为特定域名的邮箱
   * filter.likeLeft('user.email', 'example.org');
   * // 生成: user.email LIKE '%example.org'
   *
   * @param field 字段名
   * @param value 值
   * @returns 当前过滤器实例，支持链式调用
   */
  public likeLeft(field: keyof T | string, value: string): this {
    this.builder.likeLeft(field, value);
    return this;
  }

  /**
   * 添加右模糊匹配条件（匹配以特定字符开头的字符串）
   *
   * @example
   * // 添加右模糊匹配条件
   * filter.likeRight('name', 'Jo');
   * // 生成: name LIKE 'Jo%'
   *
   * // 匹配以特定前缀开头的产品编号
   * filter.likeRight('product.code', 'ABC');
   * // 生成: product.code LIKE 'ABC%'
   *
   * @param field 字段名
   * @param value 值
   * @returns 当前过滤器实例，支持链式调用
   */
  public likeRight(field: keyof T | string, value: string): this {
    this.builder.likeRight(field, value);
    return this;
  }

  /**
   * 添加NOT LIKE条件
   *
   * @example
   * // 添加NOT LIKE条件
   * filter.notLike('email', 'spam');
   * // 生成: email NOT LIKE '%spam%'
   *
   * // 排除包含特定关键词的评论
   * filter.notLike('comment.content', 'offensive');
   * // 生成: comment.content NOT LIKE '%offensive%'
   *
   * @param field 字段名
   * @param value 值
   * @returns 当前过滤器实例，支持链式调用
   */
  public notLike(field: keyof T | string, value: string): this {
    this.builder.notLike(field, value);
    return this;
  }

  /**
   * 添加模糊搜索条件（搜索多个字段）
   *
   * @example
   * // 搜索多个字段中包含特定值的记录
   * filter.search(['firstName', 'lastName', 'email'], 'john');
   * // 生成: firstName LIKE '%john%' OR lastName LIKE '%john%' OR email LIKE '%john%'
   *
   * // 使用AND连接，要求所有字段都包含特定值
   * filter.search(['title', 'description', 'tags'], 'urgent', 'AND');
   * // 生成: title LIKE '%urgent%' AND description LIKE '%urgent%' AND tags LIKE '%urgent%'
   *
   * @param fields 要搜索的字段列表
   * @param value 搜索值
   * @param logicalOperator 字段之间的逻辑关系
   * @returns 当前过滤器实例，支持链式调用
   */
  public search(
    fields: Array<keyof T | string>,
    value: string,
    logicalOperator: LogicalOperator = LOGICAL_OPERATOR.OR
  ): this {
    this.builder.search(fields, value, logicalOperator);
    return this;
  }

  /**
   * 添加JSON字段条件
   *
   * @example
   * // 查询JSON字段中的特定属性
   * filter.jsonField('data', '$.preferences.theme', '=', 'dark');
   * // 生成: JSON_EXTRACT(data, '$.preferences.theme') = 'dark'
   *
   * // 查询JSON数组中的值
   * filter.jsonField('user.tags', '$[0]', '=', 'premium');
   * // 生成: JSON_EXTRACT(user.tags, '$[0]') = 'premium'
   *
   * // 使用比较操作符
   * filter.jsonField('settings', '$.notifications.count', '>', 5);
   * // 生成: JSON_EXTRACT(settings, '$.notifications.count') > 5
   *
   * @param field JSON字段名
   * @param jsonPath JSON路径
   * @param operator 操作符
   * @param value 值
   * @returns 当前过滤器实例，支持链式调用
   */
  public jsonField(
    field: keyof T | string,
    jsonPath: string,
    operator: string,
    value: any
  ): this {
    this.builder.jsonField(field, jsonPath, operator as any, value);
    return this;
  }

  /**
   * 添加复杂条件表达式
   *
   * @example
   * // 复杂日期条件
   * filter.expr(ctx => `${ctx.field('createdAt')} >= datetime('now', '-7 days')`);
   * // 生成: createdAt >= datetime('now', '-7 days')
   *
   * // 结合多个字段的条件
   * filter.expr(ctx => `${ctx.field('price')} * ${ctx.field('quantity')} > 1000`);
   * // 生成: price * quantity > 1000
   *
   * // 使用SQLite函数
   * filter.expr(ctx => `LOWER(${ctx.field('email')}) LIKE '%@gmail.com'`);
   * // 生成: LOWER(email) LIKE '%@gmail.com'
   *
   * // 复杂日期比较
   * filter.expr(ctx =>
   *   `JULIANDAY(${ctx.field('endDate')}) - JULIANDAY(${ctx.field('startDate')}) > 30`
   * );
   * // 生成: JULIANDAY(endDate) - JULIANDAY(startDate) > 30
   *
   * @param expr 条件表达式函数
   * @param logicalOperator 逻辑操作符
   * @returns 当前过滤器实例，支持链式调用
   */
  public expr(
    expr: (ctx: { field: (name: keyof T | string) => string }) => string,
    logicalOperator: LogicalOperator = LOGICAL_OPERATOR.AND
  ): this {
    this.builder.expr(expr, logicalOperator);
    return this;
  }

  /**
   * 添加多个字段与值比较的条件组合
   *
   * @example
   * // 多字段精确匹配
   * filter.multiEq(['firstName', 'lastName'], ['John', 'Doe']);
   * // 生成: firstName = 'John' AND lastName = 'Doe'
   *
   * // 带表别名
   * filter.multiEq(['user.city', 'user.country'], ['New York', 'USA']);
   * // 生成: user.city = 'New York' AND user.country = 'USA'
   *
   * @param fields 字段名数组
   * @param values 值数组
   * @returns 当前过滤器实例，支持链式调用
   */
  public multiEq(fields: Array<keyof T | string>, values: any[]): this {
    this.builder.multiEq(fields, values);
    return this;
  }

  /**
   * EXISTS子查询条件
   *
   * @example
   * // 查询有订单的用户
   * filter.exists('SELECT 1 FROM orders WHERE orders.userId = users.id');
   * // 生成: EXISTS (SELECT 1 FROM orders WHERE orders.userId = users.id)
   *
   * // 带参数的子查询
   * filter.exists(
   *   'SELECT 1 FROM orders WHERE orders.userId = users.id AND orders.status = @status',
   *   { status: 'completed' }
   * );
   * // 生成: EXISTS (SELECT 1 FROM orders WHERE orders.userId = users.id AND orders.status = 'completed')
   *
   * @param subquerySql 子查询SQL语句
   * @param params 子查询参数
   * @returns 当前过滤器实例，支持链式调用
   */
  public exists(subquerySql: string, params?: Record<string, any>): this {
    this.builder.exists(subquerySql, params);
    return this;
  }

  /**
   * NOT EXISTS子查询条件
   *
   * @example
   * // 查询没有订单的用户
   * filter.notExists('SELECT 1 FROM orders WHERE orders.userId = users.id');
   * // 生成: NOT EXISTS (SELECT 1 FROM orders WHERE orders.userId = users.id)
   *
   * // 查询没有特定类型评论的文章
   * filter.notExists(
   *   'SELECT 1 FROM comments WHERE comments.postId = posts.id AND comments.type = @type',
   *   { type: 'negative' }
   * );
   * // 生成: NOT EXISTS (SELECT 1 FROM comments WHERE comments.postId = posts.id AND comments.type = 'negative')
   *
   * @param subquerySql 子查询SQL语句
   * @param params 子查询参数
   * @returns 当前过滤器实例，支持链式调用
   */
  public notExists(subquerySql: string, params?: Record<string, any>): this {
    this.builder.notExists(subquerySql, params);
    return this;
  }

  /**
   * 日期条件 - 在指定日期范围内
   *
   * @example
   * // 查询在特定日期范围内创建的记录
   * const startDate = new Date('2023-01-01');
   * const endDate = new Date('2023-12-31');
   * filter.dateBetween('createdAt', startDate, endDate);
   * // 生成: createdAt BETWEEN '2023-01-01' AND '2023-12-31'
   *
   * // 查询指定期限内的活动
   * const now = new Date();
   * const nextWeek = new Date(now);
   * nextWeek.setDate(now.getDate() + 7);
   * filter.dateBetween('event.date', now, nextWeek);
   * // 生成: event.date BETWEEN '2023-06-01' AND '2023-06-08' (举例)
   *
   * @param field 日期字段名
   * @param startDate 开始日期
   * @param endDate 结束日期
   * @returns 当前过滤器实例，支持链式调用
   */
  public dateBetween(field: keyof T | string, startDate: Date, endDate: Date): this {
    this.builder.dateBetween(field, startDate, endDate);
    return this;
  }

  /**
   * 添加原始SQL条件片段
   *
   * @example
   * // 使用SQL函数
   * filter.rawWhere('EXTRACT(YEAR FROM date) = 2023');
   * // 生成: EXTRACT(YEAR FROM date) = 2023
   *
   * // 带参数
   * filter.rawWhere('LOWER(name) = @name', { name: 'john' });
   * // 生成: LOWER(name) = 'john'
   *
   * // 使用OR连接
   * filter.eq('status', 'active')
   *   .or()
   *   .rawWhere('DATEDIFF(NOW(), created_at) < 7');
   * // 生成: status = 'active' OR DATEDIFF(NOW(), created_at) < 7
   *
   * // 复杂JSON查询
   * filter.rawWhere("JSON_EXTRACT(data, '$.preferences.theme') = 'dark'");
   * // 生成: JSON_EXTRACT(data, '$.preferences.theme') = 'dark'
   *
   * @param sql 原始SQL片段
   * @param params 可选的参数对象
   * @param logicalOperator 逻辑操作符（默认为AND）
   * @returns 当前过滤器实例，支持链式调用
   */
  public rawWhere(
    sql: string,
    params?: Record<string, any>,
    logicalOperator: LogicalOperator = LOGICAL_OPERATOR.AND
  ): this {
    this.builder.rawWhere(sql, params, logicalOperator);
    return this;
  }

  /**
   * 添加批量条件处理
   *
   * @example
   * // 批量添加多个条件（对象格式）
   * filter.batchWhere([
   *   { field: 'name', operator: '=', value: 'John' },
   *   { field: 'age', operator: '>', value: 18 }
   * ]);
   * // 生成: name = 'John' AND age > 18
   *
   * // 使用数组格式
   * filter.batchWhere([
   *   ['status', '=', 'active'],
   *   ['createdAt', '>', '2023-01-01']
   * ]);
   * // 生成: status = 'active' AND createdAt > '2023-01-01'
   *
   * // 使用OR连接
   * filter.batchWhere([
   *   ['category', '=', 'electronics'],
   *   ['category', '=', 'computers']
   * ], 'OR');
   * // 生成: category = 'electronics' OR category = 'computers'
   *
   * @param conditions 条件数组
   * @param logicalOperator 条件之间的逻辑操作符
   * @returns 当前过滤器实例，支持链式调用
   */
  public batchWhere(
    conditions: Array<{ field: keyof T | string; operator: string; value: any } | [keyof T | string, string, any]>,
    logicalOperator: LogicalOperator = LOGICAL_OPERATOR.AND
  ): this {
    this.builder.batchWhere(conditions as any, logicalOperator);
    return this;
  }

  /**
   * 添加匹配多个值的条件（IN子查询）
   *
   * @example
   * // 匹配ID在子查询结果中的记录
   * filter.matchesArray('id', 'SELECT userId FROM active_sessions');
   * // 生成: id IN (SELECT userId FROM active_sessions)
   *
   * // 带参数的子查询
   * filter.matchesArray(
   *   'product.id',
   *   'SELECT productId FROM featured_products WHERE category = @category',
   *   { category: 'electronics' }
   * );
   * // 生成: product.id IN (SELECT productId FROM featured_products WHERE category = 'electronics')
   *
   * @param field 字段名
   * @param subquery 子查询SQL
   * @param params 子查询参数
   * @returns 当前过滤器实例，支持链式调用
   */
  public matchesArray(field: keyof T | string, subquery: string, params?: Record<string, any>): this {
    // 创建IN子查询条件
    const processedField = this.builder['processFieldName'](field as string);
    this.builder.rawWhere(`${processedField} IN (${subquery})`, params);
    return this;
  }

  /**
   * 添加日期周期条件
   *
   * @example
   * // 查询本周内的记录
   * filter.datePeriod('createdAt', 'week');
   * // 生成: createdAt >= date('now', 'weekday 0', '-7 days') AND createdAt < date('now', 'weekday 0', '+1 days')
   *
   * // 查询本月内的记录
   * filter.datePeriod('order.date', 'month');
   * // 生成: order.date >= date('now', 'start of month') AND order.date < date('now', 'start of month', '+1 month')
   *
   * // 查询今年内的记录
   * filter.datePeriod('transaction.date', 'year');
   * // 生成: transaction.date >= date('now', 'start of year') AND transaction.date < date('now', 'start of year', '+1 year')
   *
   * @param field 日期字段名
   * @param period 日期周期 ('day'|'week'|'month'|'year')
   * @returns 当前过滤器实例，支持链式调用
   */
  public datePeriod(field: keyof T | string, period: 'day' | 'week' | 'month' | 'year'): this {
    const processedField = this.builder['processFieldName'](field as string);

    switch (period) {
      case 'day':
        this.builder.rawWhere(`${processedField} >= date('now', 'start of day') AND ${processedField} < date('now', 'start of day', '+1 day')`);
        break;
      case 'week':
        this.builder.rawWhere(`${processedField} >= date('now', 'weekday 0', '-7 days') AND ${processedField} < date('now', 'weekday 0', '+1 days')`);
        break;
      case 'month':
        this.builder.rawWhere(`${processedField} >= date('now', 'start of month') AND ${processedField} < date('now', 'start of month', '+1 month')`);
        break;
      case 'year':
        this.builder.rawWhere(`${processedField} >= date('now', 'start of year') AND ${processedField} < date('now', 'start of year', '+1 year')`);
        break;
    }

    return this;
  }

  /**
   * 转换为条件数组
   *
   * @example
   * // 将过滤器条件转换为数组格式
   * const filter = SqlFilter.create<User>()
   *   .eq('status', 'active')
   *   .gt('age', 18);
   *
   * const conditions = filter.toArray();
   * // 返回: [
   * //   { field: 'status', operator: '=', value: 'active', logic: 'AND' },
   * //   { field: 'age', operator: '>', value: 18, logic: 'AND' }
   * // ]
   *
   * // 序列化为JSON
   * const jsonConditions = JSON.stringify(filter.toArray());
   *
   * @returns 条件对象数组
   */
  public toArray(): Array<{ field: string; operator: string; value: any; logic: string }> {
    return this.builder.toArray();
  }

  /**
   * 添加自定义参数
   *
   * @example
   * // 添加自定义参数
   * filter.withParameters({
   *   userId: 123,
   *   startDate: '2023-01-01'
   * });
   *
   * // 结合原始SQL片段使用
   * filter.withParameters({ threshold: 1000 })
   *   .rawWhere('price * quantity > @threshold');
   * // 生成: price * quantity > 1000
   *
   * @param params 参数对象
   * @returns 当前过滤器实例，支持链式调用
   */
  public withParameters(params: Record<string, any>): this {
    Object.assign(this.builder['parameters'], params);
    return this;
  }
}
